---
title: Retroboot maintenance manual
x-toc-enable: true
...

This document describes how to maintain `rbmk` (Retroboot Make). If you just
want to *build it*, refer to this document instead:
[How to build Retroboot from source](../git/)

Retroboot's build system is named `rbmk`, short for `Retroboot Make`, and this
document describes every aspect of how it works. You can use this document as
a reference for modifying `rbmk`.
**This document assumes that you are using the Retroboot git repository, which
you can download here:
<https://notabug.org/retroboot/retroboot>**

If you're using a release archive of Retroboot, please refer to the
documentation included with *that* release. It will be an older version of the
document that you're now reading. For *development*, we prefer that you modify
`rbmk` in the *Git repository* and read this document as a reference.

If you've made changes to Retroboot and you wish to submit them for review,
you can! Refer to the following document:
[Sending patches for review](../../contrib.md)

Use the Git repository!
=======================

An overview of Retroboot:
-------------------------

As of 5 January 2021, any command in the build system can run and, if required
pre-requisite steps are not performed, the build system will run the
necessary commands. For example, if you run `./build module grub` but a
GRUB directory is not present, the build system will automatically run
`./download grub`. This also means that you can now, from a fresh Git clone of
Retroboot, simply run `./build retroboot roms` and it will work!

In the git repository, Retroboot does not actually host projects such as
coreboot, GRUB or SeaBIOS. Retroboot is, in a nutshell, a series of scripts
that define how to:

* Download all of the required software components
* Patch all of the required software components, where necessary
* Build all of the required software components
* Build ROM images

Basically, Retroboot is mostly "metadata" defining where to grab everything
and how to put it all together, from start to finish. No actual development
on upstream projects (coreboot, GRUB, SeaBIOS etc) is done directly within
Retroboot; development is done upstream, when development is done.

Another way of thinking about it is this: Retroboot is a recipe for building
coreboot ROM images, much like a recipe for cake tells you how to prepare
and bake a cake.

Retroboot doesn't just contain such scripts. It also contains:

- config files (for board configs, payloads, etc)
- option ROMs (e.g. for VGA initialization on boards without libgfxinit support)
- 3rd party submodules from coreboot. This is available under `3rdparty/` under
  each coreboot directory, for each board

You can also think of it as a "package manager". Development within Retroboot
is done purely on the build scripts that download, patch, build and integrate
everything, which then results in tested ROM images at known good versions of
each and every software component.

This document assumes that you have downloaded Retroboot from the Git repository.
If you are using a source code release archive, you can *skip* the download
commands.

It is *strongly* recommended that you always build from Git, not the release
archives. Technically, you can do whatever you want, but the releases are
considered *reference* level, with source code included simply for GNU GPLv2/3
compliance and such. For actual development, you should use the Git repository.

In some cases, if you don't intend to develop Retroboot upstream but you simply
want to make a quick modification to the version you're using, then working on
the source code release archives would make sense. However, such a use-case
scenario is not covered in this document. This page (at least the one hosted
on retroboot.org) is geared towards the Git repository.

Let's begin!

Build dependencies
------------------

Before you begin, you should install all of the pre-requisite build
dependencies so that you can compile Retroboot. These can be installed by
running the following command in the build system (tested on Ubuntu 20.04):

    ./build dependencies ubuntu2004

Simply speaking, this runs a script that automatically installs all of the
build dependencies in apt-get.

How to build Retroboot from source
----------------------------------

Before you begin working on the build system, and reading the information on
this page, it can help to get a high level view of how the build system is
*used*. We already provide such documentation:

[Learn how to compile Retroboot from source](../git/)

Main build scripts
==================

Retroboot's build system is highly centralized: all build commands revolve
around two scripts:

- `./download` (runs scripts under `resources/scripts/download/`)
- `./build` (runs scripts under `resources/scripts/build/`)

The `download` script downloads modules.

The `build` script builds them.

A `meclean` script is also included. This runs the `me_cleaner` utility. It's
not required for building anything in Retroboot, but the `download` script can
download `me_cleaner`. The `meclean` script lets you run `me_cleaner` on a batch
of ROM images.

Retroboot's build system is highly modular. For the most part, individual
scripts within Retroboot are not tied to each other, and can be replaced or
modified very easily, without affecting other parts of the build system too
much, if at all. It is designed specifically to be easily adaptable, in this
manner.

Everything used by the main build scripts (`download` and `build`) uses
resources under the `resources/` directory from the root of the Git repository
or source code archive.

Resources directory
===================

Everything in the Retroboot build system exists under the `resources/`
directory. The only exception to this is the `docs/` and `www/` directory,
which are their own directory relative to the root of the main directory in
the Git repository or Retroboot source code archive.

resources/util/
---------------

This directory contains utilities that are included as part of Retroboot, and
not downloaded as *modules* like many parts of Retroboot are.

resources/util/ich9utils/
-------------------------

This is the `ich9utils` directory for source code of the following programs:

* `ich9gen`
* `ich9deblob`
* `ich9show`
* `demefactory`

Assuming you have basic dependencies such as GCC installed, simply type `make`
in this directory to compile these utilities. Related commands in the Libreboot
build system:

    ./build module ich9utils
    ./build descriptors ich9m

These utilities have everything to do with manipulating ICH9M based Intel
Flash Descriptors on GM45 laptops such as ThinkPad X200 or T400. These were
adapted from Libreboot.

More documentation about ICH9M and `ich9utils` is littered throughout the
Retroboot documentation.

resources/blobs/pciroms/
------------------------

This directory is intended for PCI Option ROM files, for instance Video BIOS
ROM images. These can be loaded and executed by coreboot, or by SeaBIOS.

The file must be named with following convention: `pciVVVV,DDDD.rom`

VVVV is the vendor ID and DDDD is the device ID. These numbers can be obtained
by running `lspci -nn` in GNU+Linux. You will see it listed as VVVV:DDDD.
For example, an option ROM from PCI ID 1002:7145 would be `pci1002,7145.rom`.

NOTE: SeaVGABIOS option ROM is not stored here. It is stored under
the directory `payload/seabios/` as `seavgabios.bin` when running the command
`./build payload seabios` in the Retroboot build system. SeaVGABIOS is a free
option ROM built from SeaBIOS source code, which makes use of libgfxinit
in coreboot when using native video initialization in coreboot (as opposed to
the vendor VBIOS Option ROM) on systems that have native video support in
coreboot. Using coreboot's framebuffer as a base, SeaVGABIOS emulates a Video
BIOS for legacy VGA support.

resources/coreboot/
-------------------

This directory contains individual subdirectories for each board supported
in Retroboot (whether it's a laptop, desktop or server mainboard). It contains
config files, patches, information about coreboot/3rdparty commit IDs and so
on. It reproducibly downloads and patches coreboot, for several mainboards that
are supported in the Retroboot build system.

Inside each is the following:

### resources/coreboot/BOARD\_NAME/romtype

This file is *optional*.

Put a single line of text here, which can be anything. Specific lines of text
can be used to instruct the ROM build script. Those are:

* `4MiB IFD BIOS region` (if specified, the 4MiB BIOS region will be extracted
  which is actually just 4MiB CBFS size. For instance, `x230_4mb` ROMs are
  provided in Retroboot because X230 splits its 12MiB NOR flash into 8MiB and
  4MiB chips, with upper 3MiB of the 8MiB flash being first part of the default
  BIOS region unless IFD is modified, with the 4MiB chip containing the final
  upper 4MiB part of the BIOS region. These 4MiB ROMs are useful when flashing,
  to flash just that 4MiB chip)
* `4MiB ICH9 IFD NOR flash` (instructs the ROM script to insert ICH9M flash
  descriptor with disabled ME, on GM45/ICH9 boards such as ThinkPad X200/T400.
  This one is for 4MiB NOR flash)
* `8MiB ICH9 IFD NOR flash` (same as above but for 8MiB NOR flash)
* `16MiB ICH9 IFD NOR flash` (same as above but for 16MiB NOR flash)
* `i945 laptop` (if this is specified, the upper 64KiB bootblock will be copied
  to the space for the lower 64KiB bootblock, in the resulting coreboot ROM.
  This is useful for BUC.TS purposes on machines such as ThinkPad X60/T60)

As of 5 January 2021, no other strings are specified in the build system, so
anything else (or the `romtype` file being absent) will result in default
behaviour: just copy the ROM but don't modify it in any way.

In this configuration, the descriptor specifies regions based on 16MiB NOR flash.

### resources/coreboot/BOARD\_NAME/x86\_32

This file is optional. If present, Tianocore will not be included at all when
building ROM images.

Only the 64-bit version of Tianocore is built in Retroboot's build system.
Some machines are 32-bit only, and in practise those older machines are
typically quite useless with Tianocore.

Tianocore is only really useful on 64-bit machines, in most use-case scenarios,
so Retroboot only builds the 64-bit version.

### resources/coreboot/BOARD\_NAME/config/

The following files (at least one, or all) can be included:

* `libgfxinit_txtmode`
* `libgfxinit_vesafb`
* `vgarom_txtmode`
* `vgarom_vesafb`

Configs with `vgarom` in the name must specify a PCI option ROM file name
under format `pciVVVV,DDDD.rom` where VVVV is the vendor ID and DDDD is the
device ID. This option ROM will be under `resources/blobs/pciroms/`
and the config: 1) disables VBT in coreboot, 2) Disables libgfxinit if present
and 3) Enables loading and executing of PCI option ROM (Video BIOS) for that
video chipset, with the exact PCI ID specified in the coreboot config.

Configs with `libgfxinit` in the name must specify that libgfxinit is to be
used, with a VBT (Video BIOS Table) supplied by coreboot. Loading of PCI option
ROMs must not be enabled in this setup (but on desktops, where libgfxinit is
used for the built-in GPU, an add-on GPU can still be used if you use the
SeaBIOS payload, because SeaBIOS will automatically load the Video BIOS from
your graphics card).

Regardless of whether you use `vgarom` or `libgfxinit` setup:

* `txtmode` specifies that coreboot must start in legacy VGA text mode. This is
  useful for textmode applications such as MemTest86+ or operating systems such
  as FreeDOS
* `vesafb` specifies that coreboot must start in a VESA framebuffer. This option
  is most useful combined with `libgfxinit` when dealing with GNU+Linux or BSD
  operating systems in the GNU GRUB payload, or in SeaBIOS with SeaVGABIOS.
  This mode is also implied when using Tianocore, and Retroboot's build system
  does not provide Tianocore ROMs with `txtmode` startup.

These are specific coreboot configs for that board. These configs do not
specify a payload, but enable PS/2 keyboard initialization in case SeaBIOS
and GRUB are used (other payloads such as linuxboot and tianocore can do
keyboard initialization on their own).

Each of these are coreboot configurations, for that board.

The rules (for Retroboot purposes) are as follows:

* Payload must be set to *None*. The Retroboot build system builds payloads
  externally, instead of using the coreboot build system.
* VGA ROM must be included, if required, and set in coreboot config such that
  coreboot itself is loading and executing the ROM.
* The config must not make coreboot's build system grab anything from
  external sources, *except* the `3rdparty` repositories hosted by the
  coreboot project. The Retroboot build system provides the chance to specify
  exactly which 3rdparty submodule revisions are used. 3rdparty modules are
  downloaded *after* setting the coreboot revision, to ensure a consistent
  set of 3rdparty modules, and then resets the revisions of each submodule
  based on what is written in the Retroboot build system
* NOTE: exception to above rule is VGA ROMs, and other PCI option ROMs, which
  the user may want to include. However, only VGA option ROMs are really
  useful in most cases. Normally for other options ROMs, the user would
  want to have the SeaBIOS payload

General rules/principles for configuring a board in `make menuconfig` on the
coreboot build system:

* `General -> Use CMOS for configuration values` (ENABLE)
* `General -> Load default configuration values into CMOS on each boot` (ENABLE)
* Hardcode your own desired CMOS config
  in `src/mainboard/manufacturer_name/mainboard_name/cmos.default`
* It's possible to change the CMOS config in nvramtool, directly on the ROM
  image. Simply dump it, change the value you want, then re-flash. Hardcoded
  config is desired, for consistent functionality on all systems where a given
  ROM image is used. This makes Retroboot behave more consistently at startup.
* Select what mainboard you want under `Mainboard`
* If it's a system with Intel Flash Descriptor, set the CBFS size to exactly
  the size of the BIOS region (as per Intel Flash Descriptor). For example,
  on X230, coreboot sets 1MiB CBFS size by default but the default BIOS region
  is 4MiB, so:
    * `Mainboard -> Size of CBFS filesystem in ROM = 0x400000`
      (this is 4MiB specified in bytes as a hexadecimal value)
* Chipset -> Include CPU microcode in CBFS = Generate from tree
  (REQUIRED. If microcode updates are available, you should include them
  because they fix bugs and security issues that exist in the default burned in
  microcode on the CPU. However, some non-x86 machines such as Rockchip ARM
  SoCs might not use microcode at all)
* `Chipset -> Bootblock behaviour = Always load fallback`
  Based on a setting in CMOS memory, coreboot's bootblock can load either the
  `fallback` or `normal` payload. You can also put different ramstage and
  romstage in cbfs. This is useful for development, but not really useful for
  end users that Retroboot is targeting.
  (the Retroboot build system currently does not support use of fallback+normal
  but this could change in the future. Coreboot provides a mechanism where you
  put a setting in CMOS config that makes fallback/normal be used depending
  on that setting. If the RTC battery is pulled, then the other payload will
  be used. This other payload can be anything. This is useful
  for development purposes, like when developing a payload. You can have a
  known working payload, and the one you're working on, to prevent soft bricks
  and speed up development. Retroboot is geared towards end users, so just
  always use the fallback, and only include a fallback payload as
  `fallback/payload` in CBFS. This is the default behaviour of the Retroboot
  build system. This is OK because we verify each setup before releasing it.
* `Devices -> Graphics initialization = Use libgfxinit`
    * If you use this option, also do:
    * `Add a Video BIOS Table (VBT) binary to CBFS (NEW) = ENABLED`
    * `Display -> Framebuffer mode = whatever you want`
    * `txtmode` in the config name if setting legacy VGA framebuffer
    * `vesafb` in the config name if setting vesa framebuffer with a higher resolution
* Devices -> Graphics initialization = Run VGA Option ROMs
    * If you use this option, also do:
    * Display -> Leave it alone if you just want text mode (legacy VGA mode)
    * Display -> Select a resolution and set Framebuffer mode to VESA framebuffer
      if you want a high resolution framebuffer at startup
    * Add a VGA BIOS image = ENABLED
    * Include the PCI option ROM from `resources/blobs/pciroms/` (see below)
      and in in coreboot menuconfig specify the filename as `pciVVVV,DDDD.rom`
      where VVVV is the vendor ID and DDDD is the device ID. You can find
      this information by running `lspci -nn` under GNU+Linux, and you can
      check that the option ROM is for your specific VGA adapter by running
      `romheaders` utility on the ROM. Check build date and other information
      of the VGA ROM by running `strings pciVVVV,DDDD.rom | head`
    * Example entry for path to VGA ROM in coreboot menuconfig:
      `../../resources/blobs/pciroms/pciVVVV,DDDD.rom`
    * `Add a Video BIOS Table (VBT) binary to CBFS = DISABLE` (it's VERY
      important to disable this option, because the VGA ROM itself will handle
      VBT stuff and you don't want to conflict anything at start up)
* `Generic Drivers -> PS/2 keyboard init = DISABLE`
    * Only enable if necessary, like if you actually need to have PS/2
      keyboard support, otherwise USB keyboard support will usually Just Work.
      GRUB, SeaBIOS and Tianocore all provide PS/2 keyboard init.
    * Tianocore (UEFI) payload does not require this option to be enabled. It
      handles PS/2 keyboard initialization by itself
    * Don't enable "PS/2 keyboard delay" in coreboot menuconfig. The Retroboot
      build system adds this externally, using a `cbfstool` command
* `Security -> Memory initialization -> Always clear all DRAM on regular boot =
  ENABLE`
    * This helps to reduce the threat posed by Cold Boot attacks
    * Other security features here you can choose to enable or disable
      depending on your preferences
* `Console -> Default console log level = 0`
    * Retroboot is intended for end users, who want a faster boot speed
    * The extra debug options slow down the boot process
* `Payload -> Add a payload = NONE`
    * Retroboot's build system compiles payloads externally, and adds them
      during the build process using `cbfstool`

### resources/coreboot/BOARD\_NAME/patches/

**NOTE: This directory is ignored when you include a symlink file (see below)**

You can make modifications to coreboot, on the upstream coreboot repository,
reset to whatever coreboot commit ID you want to base your patches on.

For however many custom patches you've applied, run the following command:

    git format-patch -nX

X is the number of patches. This might be applied in the `master` branch, or
you might be working on another branch. If you're working in another branch,
the commit ID is from whatever commit that branch forks from.

Retroboot's build system does not remove `.git` resources from coreboot,
when downloading it for each board. Therefore, even if you've already applied
patches (using the build system from Retroboot), you can then make further
modifications on top of coreboot and include your patch.

The patches must be in ascending alpanumerical order from the first patch to
be applied.

For example:

* `0001-first.patch`
* `0002-second.patch`
* `0003-third.patch`
* ...and so on

NOTE: If you're using a symlink file (see below), do not put the patches here.
In that situation, the patch directory should be empty (but the directory
should still be present). For example, let's say X220 uses the same coreboot
revision as X230, with X220 having a symlink file pointing to the X230
directory.

If symlink file present, put your patches in the `patch/` directory of the
board that is being linked to instead.

### resources/coreboot/BOARD\_NAME/revision/

**NOTE: This directory is ignored when you include a symlink file (see below)**

This directory contains files with single lines in them, specifying the exact
commit ID of each coreboot submodule that go inside the `3rdparty/` directory
of the coreboot Git repository.

Download coreboot and reset it to the revision you wish to use. Then you can
download the submodules using this command:

    git submodule update --init --checkout

Check the `.gitmodules` file in your coreboot directory. It specifies where
all of the 3rdparty submodules will be downloaded to. Most of them will be
downloaded into the `3rdparty/` directory.

For the ones in `3rdparty/` you should put a file with the same name as the
corresponding directory under `3rdparty/` with that file containing just a
single line specifying the commit ID you wish to use.

Generally, you should always set the 3rdparty revisions to the same ones used
when you first downloaded the 3rdparty submodules in that version of coreboot,
when *that* commit ID was the newest one in coreboot. This is because the
submodule commit IDs will always be the latest ones in that repository, even
when resetting to an older coreboot revision (Retroboot resets to the coreboot
revision specified in cbrevision, see below).

If you are *retroactively* selecting an older coreboot revision, you should
set the 3rdparty submodule revisions to ones that are either the exact same
commit date as the date of the coreboot commit or, if none are that exact date,
the latest date(s) *before* the date of the coreboot commit, *not* after. This
will be verified when you submit a pull request anyway.

NOTE: Not all 3rdparty submodules are downloaded into `3rdparty/`, and those
ones will not automatically be reset to a specific revision by the Retroboot
build system. For these, you should reset the commit using the `extra.sh`
script (see below).

### resources/coreboot/BOARD\_NAME/cbrevision

**NOTE: This file is ignored when you include a symlink file (see below).**

This file must contain a single line, with no whitespace, just specifying
the commit ID of the coreboot revision you intend to use (as per the coreboot
Git repository).

### resources/coreboot/BOARD\_NAME/extra.sh (optional)

Technically, this script is optional but if you are not specifying a symlink
via `symlink` file (see below) you should always, at the very least, reset
submodule revisions of coreboot in this script, for those submodules that
are *not* downloaded into the `3rdparty/` subdirectory of coreboot.

This is useful if you want to extend the default functionality of the build
in Retroboot, for the particular board you're working on.

For example, if coreboot is downloading some submodules to a directory other
than `3rdparty/` in the coreboot Git repository, you should script something in
here to reset the revision of *that* submodule.

Another example of how this `extra.sh` script can be used is to apply custom
patches to *submodules* in coreboot, or any other such functionality that is
not yet implemented by the main build system in Retroboot. In other words,
extra.sh can be used to extend the Retroboot build system functionality!
That's why it's called `extra.sh`!

However, Retroboot's build system is released under a free license and you're
free to extend it anyway. However! Sometimes, you will want to implement
specific functionality that only benefits one specific mainboard in Retroboot.
You could *also* make the `extra.sh` script symlink to *another* `extra.sh`
script.

### resources/coreboot/BOARD\_NAME/symlink (optional)

When you run the `./download coreboot` command, or coreboot is downloaded when
running the `./download all` command, coreboot is only downloaded (via git
clone) *once*, and then copied (using `cp -R`) for *each* board specified as
per directory names under `resources/coreboot/`.

A separate coreboot directory for each board is therefore created. For example,
X230's coreboot directory would be `coreboot/x230_4mb/`. Coreboot's own crossgcc
toolchain, utilities and other modules are compiled *separately*, for each
directory. This means that different coreboot revisions can be used for
different boards.

However, in practise we often use the same coreboot revision for most boards,
or at most 2-3 coreboot revisions are used and each revision has a few boards
using it in the Retroboot build system. It would be a waste to create a
separate coreboot directory for multiple boards that all use the same coreboot
revision.

Therefore, Retroboot's build system supports linking to another board, thus
skipping the creation of a new coreboot directory. 

The `symlink` file is not actually a symlink, but instead should contain the
board name, per directory name of that board under `resources/coreboot/`.

The build system goes into the `coreboot/` directory and creates a relative
symlink. For example, if X220 contained a symlink pointing to X230, in
the `coreboot/` directory there would be a symlink `x220 -> x230_4mb`.

resources/grub/
---------------

This directory contains the GRUB configuration files (for the target systems
that Retroboot's build system contains GRUB ROMs for), GRUB fonts, keymap files
and a file specifying which modules are to be included in the GRUB payload.

### resources/grub/config/

GRUB configs. There is not a full GRUB config here, because the build system
mixed different *snippets* together to create various *full* GRUB configs, for
various setups.

To understand how these files are used, read the following script:

* `resources/scripts/build/payload/grub`

### resources/grub/font/

Fonts go in here. Currently, only the Dejavu Sans Mono is provided, as a font
used in GRUB (but only is VESA mode, not text mode).

### resources/grub/keymap/

Keymap configurations are included here, for various keyboard layouts.
Retroboot's build system provides multiple ROM images with the GRUB payload,
each with a different default payload. Even Dvorak (US, UK and French variants)
are supported! This is one reason why Retroboot is so great.

I, Leah Rowe, created the UK Dvorak keymap file by hand, many years ago, by
manually modifying the scan codes in the US Dvorak file. This is because there
was no UK Dvorak keymap file available, and automatically generating it caused
problems when actually using it. I did this many years ago, for Libreboot,
because I'm a long time Dvorak user.

If you wish to add new keymaps, you can do so using the instructions here:

[Adding new keymap files to GRUB](../grub/#grub-keyboard-layouts-for-reference)

### resources/grub/modules.list

This file contains a list of modules to be used in the GRUB payload. It is
important to not use too many, because of limited storage capacity in the main
boot flash on most systems that Retroboot has support for.

resources/memtest86plus/patch/
------------------------------

Patches for Memtest86+, which is included as a payload on certain Retroboot
configurations. It is used to test your RAM, and it will tell you if your
RAM is faulty.

resources/scripts/build/
========================

This directory contains all of the scripts used that make up the entire
Retroboot build system.

resources/scripts/build/clean/
------------------------------

Basically, these scripts do the equivalent of `make clean` or `make distclean`
on various modules thet are a part of Retroboot.

### resources/scripts/build/clean/ich9utils

This runs `make clean` on the `ich9utils` directory
at `resources/util/ich9utils/`

This also deletes the descriptors generated at `descriptors/ich9m/`

### resources/scripts/build/clean/cbutils

This runs `make clean` on the following coreboot utilities, in each coreboot
directory for each board, on the following directories in coreboot:

* `util/cbfstool/`
* `util/ifdtool/`
* `util/nvramtool/`
* `util/cbmem/`

It also runs `make distclean` on `payloads/libpayload/` in each coreboot
directory.

These directories were created when running `./download coreboot` in the
Retroboot build system.

### resources/scripts/build/clean/crossgcc

In each coreboot directory, for each board, this script does `make distclean`
on `util/crossgcc/` which is the cross-compiler toolchain that comes with
coreboot.

The crossgcc binaries were compiled when running `./build module crossgcc` in
the Retroboot build system, which in turn runs `make crossgcc` in each and
every coreboot directory created when running `./download coreboot` in the
Retroboot build system.

### resources/scripts/build/clean/flashrom

This runs `make clean` on the `flashrom/` directory, which was created when
running `./download flashrom` in the Retroboot build system.

### resources/scripts/build/clean/grub

This runs `make distclean` on the `grub/` directory, which was downloaded
when running `./download grub` in the Retroboot build system.

However, it does *not* delete the payload executables in the `payload/`
directory, which were created when running `./build payload grub`,
`./build payload seabios` or `./build payload all` in the Retroboot build
system.

The files under `payload/` are cleaned out when running the
`./build clean payloads` command.

### resources/scripts/build/clean/memtest86plus

This runs `make clean` on the `memtest86plus/` directory, which was created
when running `./download memtest86plus` in the Retroboot build system.

### resources/scripts/build/clean/payloads

This literally just deletes the `payload/` directory, which was created when
running `./build payload grub` or `./build payload seabios` or
`./build payload all` in the Retroboot build system.

### resources/scripts/build/clean/rom\_images

This literally just deletes the `bin/` directory, which was created when
running the following command in the Retroboot build system:

    ./build retroboot roms

The `bin/` directory contains coreboot ROM images, which were built when
running one of the above commands.

### resources/scripts/build/clean/seabios

This runs `make distclean` on the `seabios/` directory, which was created when
running `./download seabios` in the Retroboot build system.

resources/scripts/build/dependencies/
-------------------------------------

### resources/scripts/build/dependencies/ubuntu2004

Using the `apt-get` software, this script downloads and installs the required
build dependencies on Ubuntu 20.04, which is a GNU+Linux distribution.

In Libreboot 20160907, which Retroboot was originally forked from (on December
11th, 2020), there was also a script for Parabola GNU+Linux. However, the
Parabola script was deleted in Retroboot due to lack of testing. Libreboot
20160907 contained a script for Trisquel 7.0, which was updated for Ubuntu
20.04.

resources/scripts/build/descriptors/
------------------------------------

Various commands to do with Intel Flash Descriptors

### resources/scripts/build/descriptors/ich9m

This is executed when running `./build descriptors ich9m`

This simply runs `ich9gen` located at `resources/util/ich9utils/`

Descriptors are made available at `descriptors/ich9m/`

resources/scripts/build/module/
-------------------------------

These scripts compile the required modules, as a pre-requisite for then
compiling payloads, which in turn is a pre-requisite for compiling coreboot
ROM images for the end user to install (flash) on their machine.

### resources/scripts/build/module/ich9utils

This runs `make` on `ich9utils` included at `resources/util/ich9utils/`.

This makes the following utilities available in that directory:

* `ich9gen`
* `ich9show`
* `ich9deblob`
* `demefactory`

More information about `ich9utils` is littered throughout the Retroboot
documentation.

### resources/scripts/build/module/cbutils

This runs `make` on the following coreboot utilities:

* `util/cbfstool`
* `util/ifdtool`
* `util/nvramtool`
* `util/cbmem`

The `cbfstool` utility is used extensively by the Retroboot build system, when
building coreboot ROM images. It is used to:

* Insert payloads into the ROM images (Retroboot does not rely on the coreboot
  build system to insert payloads. They are compiled externally, and the ROM
  images are compiled with payloads. Cbfstool is then used, to insert the
  payloads *after* the coreboot ROM images are compiled)
* Insert GRUB configurations into the ROM images
* ...and more

The `ifdtool` utility is not currently used by the Retroboot build system, but
it is provided for people who use Intel platforms that have an Intel Flash
Descriptor in the boot flash. For example, X230's Intel Flash Descriptor sets
some of the flash regions read-only by default, and ifdtool can be used to
set these regions read-write by modifying the Intel Flash Descriptor in a
dump of it, which can then be re-flashed to enable internal re-flashing.

The `nvramtool` utility is not currently used by the Retroboot build system,
but it is recommended for changing CMOS settings in the coreboot ROM image.
Retroboot hardcodes these settings, but you can dump the ROM and use nvramtool
to change the defaults specified in the ROM; this modified ROM can then be
re-flashed. The reason these settings are hardcoded is to ensure consistent
behaviour of a given Retroboot ROM image, on a given system (unless the end
user changes the default behaviour, and this is documented on the Retroboot
website).

The `cbmem` utility is not currently used by the Retroboot build system, but it
is useful for debugging purposes. End users can usually ignore this one.

### resources/scripts/build/module/crossgcc

For *each and every* coreboot directory created by running `./download coreboot`
in the Retroboot build system, this script goes into said directory and runs
the following command:

    make crossgcc-i386

This is *required* for building coreboot ROM images in the Retroboot build
system. Coreboot has its own cross-compiler toolchain, which it calls *crossgcc*
and it is compiled by running the above command (in the *coreboot* build
system).

### resources/scripts/build/module/flashrom

This script runs `make` in the `flashrom/` directory, which was created when
running `./download flashrom` in the Retroboot build system.

### resources/scripts/build/module/grub

This does *not* build the actual GRUB payload, which is inserted into coreboot
ROM images for configurations that use GNU GRUB bootloader as default payload.

Rather, this script builds the required GRUB utilities when are then executed
by running `./build payload grub` in the Retroboot build system, to create
the GNU GRUB payloads (there are several different GRUB payload configurations,
which Retroboot uses for different machine configurations).

GNU GRUB can be compiled for several different systems. On x86, the most
common configuration is for BIOS or UEFI and is referred to generically as *PC
GRUB*.

Retroboot compiles GNU GRUB with the following command in GRUB's build system:

    ./configure --with-platform=coreboot

This is a special build-time configuration. When this configuration is used,
GNU GRUB runs on *bare metal* as a coreboot payload, and does not make use of
BIOS or UEFI based services. Several features are present in this version of
GRUB, that are not present in other versions. For example, the `lscoreboot`
command becomes available on the GNU GRUB terminal, which displays information
about the version of coreboot that is currently running on the end user's
machine.

### resources/scripts/build/module/memtest86plus

This script runs `make` in the `memtest86plus/` directory, which was created
when running `./download memtest86plus` in the Retroboot build system.

resources/scripts/build/payload/
--------------------------------

These scripts build the payloads (ELF executables) that are inserted into the
coreboot ROM images, when built using the Retroboot build system.

### resources/scripts/build/payload/grub

This script, using utilities compiled when running `./build module grub` in the
Retroboot build system, builds several GRUB payloads (ELF executables)
and configuration files (for the GRUB payload) and places these files in
the `payload/grub/` directory.

These files are inserted into coreboot ROM images, when
running `./build retroboot roms` in the Retroboot build system, if GRUB payload
is specified on that platform.

Essentially, there are 2 GRUB configurations per keymap (keyboard layout)
supported in the Retroboot build system:

* Config for high resolution VESA framebuffer startup in coreboot
* Config for legacy VGA text mode startup in coreboot

The `grub/grub-mkstandalone` utility is used, which was built when
running `./build module grub` in the Retroboot build system.
The `grub-mkstandalone` utility is what creates the ELF executable to then
be used in coreboot, as a payload.

It uses the following resources for this:

* GRUB config files in `resources/grub/config/`
* GRUB keymap layout files in `resources/grub/keymap/`
* GRUB modules specified in `resources/grub/modules.list`

Because these files are created seperately, in this manner, you could also
use these compiled ELF files in any coreboot ROM, not just ones compiled by
the Retroboot build system, in the situation where you built coreboot without
inserting a payload. Run the following `cbfstool` commands. Like so:

NOTE: the build system in Retroboot already does these commands, when building
ROM images. The commands below are only examples, for if you built your own
coreboot ROM by hand, and wanted to include some payloads in the ROM

For `fallback` payload in coreboot:

    cbfstool coreboot.rom add-payload -f payload/grub/filename.elf -n fallback/payload -c lzma

For `normal` payload in coreboot:

    cbfstool coreboot.rom add-payload -f payload/grub/filename.elf -n normal/payload -c lzma

For normal *or* fallback payload in coreboot, also do:

    cbfstool coreboot.rom add -f payload/grub/filename.cfg -n grub.cfg -t raw

    cbfstool coreboot.rom add -f payload/grub/filename_test.cfg -n grubtest.cfg -t raw

The `.elf` and `.cfg` must match! E.g. ELF+config for DE Qwertz keymap with
legacy VGA text mode startup.

### resources/scripts/build/payload/seabios

This script compiles two separate SeaBIOS payloads (ELF executables), using
the configuration files stored in `resources/seabios/config/`:

* `resources/seabios/config/libgfxinit`
* `resources/seabios/config/vgarom`

The `libgfxinit` config specifies that SeaBIOS must use the video initialization
in coreboot, which provides a framebuffer interface. For this purpose, SeaBIOS
will also compile its own option ROM called SeaVGABIOS, which emulates a Video
BIOS for providing legacy VGA support (however, it currently does not support
switching between different video modes and INT 10H interrupt services are not
completely functional when using this). SeaVGABIOS is useful for several things:

* SYSLINUX/ISOLINUX bootloaders, displayed on a native coreboot framebuffer
* BSD bootloaders, displayed on a native coreboot framebuffer
* Similar use case scenarios versus the above

The `vgarom` config specifies that SeaBIOS must not build its own Video BIOS
option ROM, nor should it provide any video initialization. In this
configuration, coreboot itself is loading and execution a Video BIOS option ROM
supplied by the manufacturer (e.g. Intel/AMD/Nvidia).

Both configs support all of the standard BIOS functions, which is useful for
legacy operating systems. However, INT 10H video interrupt services and
especially mode switching are not fully functional when using SeaVGABIOS. They
both load and execute PCI option ROMs, load and execute MBR based bootsectors
and in general provide a legacy BIOS interface that legacy operating systems
can use, such as DOS or old versions of Windows.

If you use the `vgarom` config, it is assumed that you will inserted a Video
BIOS option ROM supplied by the manufacturer of your video chipset, into the
coreboot ROM. For example: Intel, Nvidia or AMD/ATI option ROM.

Everything else (besides video initialization) is the same, in both SeaBIOS
configs. Which one you use is based on your own needs/preferences.

### resources/scripts/build/payload/tianocore

This script is executed when running `./build payload tianocore` in the
Retroboot build system.

This builds Tianocore UEFI payload. Currently it only builds the x86-64 setup,
so this will not currently work on 32-bit only machines such as most T60
thinkpads.

Retroboot does not directly build Tianocore. It uses a dummy coreboot config,
and uses the coreboot build system to download Tianocore. The coreboot build
system always downloads Tianocore every time you want to build it, but this
behaviour is disabled in Retroboot by a custom coreboot patch. Similarly,
coreboot always re-builds Tianocore from scratch every time; this behaviour
is also disabled.

Retroboot simply uses the Tianocore build script in the coreboot build system,
and then the Tianocore payload is available at `payload/tianocore/tianocore.elf`
in the Retroboot build system.

Coreboot's own download function for Tianocore is disabled. Retroboot downloads
Tianocore itself, using the `coreboot_fb` branch from MrChromebox's fork of
Tianocore (modified for better compatibility as a coreboot payload).

Planned: build SeaBIOS as CSM for Tianocore. This means that SeaBIOS will run
as a UEFI app. The benefit to this setup is that Tianocore provides the option
for INT10H video bios interrupt services to work in this setup, when using
legacy operating systems (e.g. old Windows versions). Currently, Retroboot
only provides a pure Tianocore setup or pure SeaBIOS setup, standalone, but
does not provide both at the same time.

resources/scripts/build/retroboot/
-----------------------------

### resources/scripts/build/retroboot/roms

This script is called when running `./build retroboot roms` in the Retroboot
build system.

This script builds all ROM images, for all payloads. In earlier versions of
Retroboot, separate coreboot configs were specified for each payload but now
they are universal. This one script builds every ROM for every payload.
In older versions, there were separate scripts for each payload config.

If no argument is given, this script will build ROM images for every board, for
every payload. However, you can specify whatever boards you want and it will
only build for that (with every payload). For example:

    ./build retroboot roms x230_4mb x220

If no special argument is given, this script will simply build *all* ROM images
as defined by configuration files in `resources/coreboot/*/config/`

No actual instructions are contained within this script, for building anything.
Instead, this script makes use of a *helper* script named `roms_helper`
which you can read about in the next section.

Each coreboot image with GRUB payload will appear under the directory at
location `bin/grub_boardname/` (SeaBIOS and Tianocore are also available to
select in the default GRUB menu).

At present, Retroboot only builds withs GNU GRUB as the default payload,
with SeaBIOS and Tianocore as an option in the menu (SeaBIOS not yet included
as CSM in Tianocore, but rather it is a standalone SeaBIOS setup).

### resources/scripts/build/retroboot/roms_helper

This script is not intended to be used directly, but it is called by the script
named `roms` under `resources/scripts/build/retroboot/`

This script builds ROM images for a single specified board. For example, the
script named `roms` may give `x230_4mb` as an argument. For the purpose of
explaining how this script works, we will assume that `x230_4mb` is the given
argument, where `roms` runs `./build retroboot roms x230_4mb`

This script makes use of the following resources:

* Coreboot source code directory at `coreboot/board_name/` where in this
  example, `board_name` is `x230_4mb`.
* Utility `cbfstool` under `coreboot/board_name/util/cbfstool/`
* SeaBIOS payload (plus SeaVGABIOS) under `payload/seabios/` (the coreboot
  images are compiled with GNU GRUB bootloader as the main payload, but SeaBIOS
  is also added and provided as an option in the GNU GRUB boot menu, as a menu
  option). When used as a coreboot payload, GNU GRUB can boot any other coreboot
  payload by using the `chainloader` command. GRUB has many advanced security
  features, unknown to most people but fully documented on the Retroboot website
  and we strongly recommend its use as default payload for your setup.
* Tianocore payload under `payload/tianocore/`
* Coreboot configuration(s) provided for a given board, located
  at `resources/coreboot/board_name/config/`
* keymap (keyboard layout) files located
  at `resources/grub/keymap/original/` to know which keymaps are supported
  and, for each one, this script compiles a coreboot ROM image with its own
  version of GNU GRUB that uses the given keymap configuration.

The coreboot configuration under `resource/coreboot/board_name/config/`
can have one of the following file names:

* `libgfxinit_txtmode`
* `libgfxinit_vesafb`
* `vgarom_txtmode`
* `vgarom_txtmode`

It is not required to have all of these files present. You may choose which
combination you would like, when adding new boards to Retroboot or modifying
existing ones.

Configs with `txtmode` in the name are for setups where coreboot initializes
the display in legacy VGA *text mode*, which is useful for legacy operating
systems such as DOS, or text mode applications like MemTest86+. It is the most
compatible option overall and, if your Video BIOS supports mode switching (which
SeaVGABIOS does not, but most vendor option ROMs do), you can switch to higher
resolution modes which means that more modern operating systems will show a
video display. (NOTE: even with text mode startup, most GNU+Linux distributions
and BSD operating systems will still show a video display, because their
kernels support *Kernel Mode Setting* where the kernel itself is controlling
video modes, without relying on Video BIOS services; this is standard practise
on Intel video chipsets, for example). If you're using a vendor-supplied VGA
ROM, it is recommended that you start in text mode as it will be the most
compatible setup (in terms of operating system support, especially if you
switch to SeaBIOS from the GNU GRUB menu).

Configs with `vesafb` in the name are for setups where coreboot initializes the
display in a high resolution VESA frame buffer. This is useful in some
situations, such as when using libgfxinit but if using text mode startup, it's
not very important. If you are using SeaVGABIOS, it's recommended to use this
setup as it will be the most compatible (with SYSLINUX/ISOLINUX bootloader menus
and such).

The `libgfxinit_txtmode` config is for setups where libgfxinit is used. This is
coreboot's own native video initialization, which coreboot provides on a lot of
mainboards nowadays. In this setup, a PCI Option ROM for the Video BIOS is not
needed because coreboot handles that functionality by itself. *Not needed* does
not mean you won't use one; you may decide (at your own discretion) that you
prefer to do so, if you wish. This setup is recommended when you wish to use
text mode applications such as MemTest86+ or boot operating systems in text
mode, such as FreeDOS (NOTE: FreeDOS will boot just fine on text mode setup
with libgfxinit, but will only run text mode applications. Games and such will
not work, because libgfxinit does not currently support mode switching)

The `libgfxinit_vesafb` config is for setups where libgfxinit is used, but you
wish to start in a high-resolution VESA framebuffer. This setup is the most
compatible, when dealing with GNU+Linux and BSD operating systems while booting
the kernel of those operating systems directly from GRUB, without relying on
SeaBIOS (which is provided in Retroboot's GRUB menu, an a menu option). It is
also the best option for SeaBIOS+SeaVGABIOS, in terms of compatibility; most
ISOLINUX/SYSLINUX boot menus will display correctly (loaded from SeaBIOS) in
this setup, albeit at a higher resolution (compared to booting from text mode
with the vendor VGA ROM, from SeaBIOS) so it might look *weird* to you at first
if you're not used to ISOLINUX/SYSLINUX menus displaying at your monitor's
native resolution. This also means that you can use SYSLINUX/ISOLINUX installed
to the HDD/SSD on your system (though, this is largely pointless because GNU
GRUB does the same things).

In addition, this build script inserts a file into CBFS (coreboot file system,
which is a file system inside the coreboot ROM that is installed onto the end
user's machine) that specifies a PS/2 keyboard delay; this makes SeaBIOS, when
loaded, wait up to three seconds for the PS/2 keyboard to initialize, if
present. This works around a potential race condition due to how fast coreboot
is capable of booting, which would otherwise prevent the keyboard from being
fully initialized, thus leaving you with a non-functioning keyboard (until
booting an OS, which would presumably handle initialization on its own).

resources/scripts/download/
===========================

The scripts in this directory download the required components that are used
in the Retroboot build system.

resources/scripts/download/coreboot
-----------------------------------

This script is executed when running the following command in the Retroboot
build system:

    ./download coreboot

First, this script checks whether a `coreboot/` directory exists. If it does
not exist, it is created. If it does exist, it is deleted and then created (to
clear what was previously there).

This `coreboot/` directory does not actually contain the coreboot Git
repository; rather, it is populated with *multiple* coreboot directories (one
for each *board*, technically, and boards specify which coreboot revision is to
be used, but boards in Retroboot can be configured to merely *link* to another
board; this means that, potentially, a single coreboot source code directory
could be used for multiple different mainboards so as to reduce waste of system
resources during the build process).

For every board defined in `resources/coreboot/` a coreboot directory is created
from a `git clone` of the official coreboot Git repository hosted at
<https://review.coreboot.org/coreboot>

If the script fails to download from the above link, it will default to the
official backup repository hosted at <https://github.com/coreboot/coreboot.git>

If both downloads fail (usually this is because your internet is down or not
connected), the script will produce an error message and exit with non-zero
status.

For each board, a dedicated coreboot source code directory is created, with
the `.git` files/directory from coreboot fully intact and:

* The commit ID is reset to a known coreboot revision, as per what is specified
  in `resources/coreboot/boardname/cbrevision`
* Coreboot submodules are downloaded by
  running `git submodule update --init --checkout` in the coreboot build system.
* For each submodule, specified in `.gitmodules` under the coreboot build
  system, the commit ID is reset to a known revision. This only applies to
  submodules that exist under `3rdparty/` in the coreboot build system, but
  a script named `extra.sh` can be supplied
  in `resources/coreboot/boardname/extra.sh` which you can make do whatever you
  want, including resetting commit IDs in other submodules not located
  at `3rdparty/` under the coreboot build system.
* For submodules that coreboot downloads into `3rdparty/`, the revisions in
  Retroboot's build system are specified
  in `resources/coreboot/boardname/revision/` by files whose file name matches
  the directory name of the submodule at `3rdparty/` (under the coreboot build
  system) and which contain a single line specifying the intended commit ID for
  use in the Git repository of that submodule (from the coreboot build system).
* Custom patches located in `resources/coreboot/boardname/patches/` are
  applied on top of that coreboot revision. This is useful for patches that
  are not yet merged in coreboot, or patches that exist in newer versions that
  you wish to use in an older version.
* Custom patches are only applied (automatically, by the Retroboot build
  system) to coreboot itself, but you can handle this for coreboot submodules
  by writing instructions in the `extra.sh` script located
  at `resources/coreboot/boardname/extra.sh`
* The `extra.sh` script is mainly intended for custom functionality, as
  a *plugin* to the Retroboot build system, when you wish to add such
  functionality when it is not useful for other boards. In cases where such
  functionality will benefit other boards, it should be implemented in the
  main build system of Retroboot, rather than inside the `extra.sh` script.
* Optionally, you can include a file named `symlink` located
  at `resources/coreboot/boardname/` containing a single line naming another
  Retroboot board (per directory name in `resources/coreboot/`). If this file
  is included, a separate coreboot directory will not be created for the given
  board that includes the given board. Instead, a symlink will be created under
  `coreboot/` pointing to the actual coreboot directory at `coreboot/otherboard`
  where `otherboard` is the other board. In this setup, the following files are
  ignored in `resources/coreboot/boardname/`:
    * `cbrevision` (specify it in the `cbrevision` file for the other board)
    * anything under `patches/` (place them in the `patches/` directory for the
      other board instead, even if they aren't needed for that board)
    * anything under `revision/` (place them in the `revision/` directory for
      the other board instead)
    * `extra.sh` (write instructions in the `extra.sh` script for the other
      board instead, if you wish)

resources/scripts/download/flashrom
-----------------------------------

This script is executed when running the following command in the Retroboot
build system:

    ./download flashrom

This downloads flashrom from the following Git repository:
<https://review.coreboot.org/flashrom.git>

The commit ID is reset to a known revision, typically a *tag* for the latest
stable release.

The repository is then available under `flashrom/` in the Retroboot build
system. Everything is self-contained in the script; typically, upstream
flashrom is used and right now there are no custom patches in use, so nothing
exists in `resources/` for flashrom and such is not accounted for by the
download script.

resources/scripts/download/grub
-------------------------------

This script is executed when running the following command in the Retroboot
build system:

    ./download grub

This downloads GNU GRUB from the following Git repository:
<git://git.savannah.gnu.org/grub.git>

If that fails, the script defaults to this Git repository:
<http://git.savannah.gnu.org/r/grub.git>

If the download fails for whatever reason, for both repository links, the
script will produce an error message and exit with non-zero status.

The commit ID is then reset to a known revision. The resulting repository is
available at `grub/` in the Retroboot build system. Everything is
self-contained in the script, and currently no patches are applied.

Since SeaBIOS is also included as an option in GRUB boot menus generated by
Retroboot, this script also runs the following command:

    ./download seabios

resources/scripts/download/me\_cleaner
--------------------------------------

This script is executed when running the following command in the Retroboot
build system:

    ./download me_cleaner

The `me_cleaner` is downloaded from the official Git repository, hosted at
<https://github.com/corna/me_cleaner.git>

The commit ID is reset to a known revision. Everything is self-contained in
this download script.

This utility is not currently used in the Retroboot build system, but a script
named `meclean` is included in the root of the Retroboot Git repository or
source code release archive. The script allows you to specify, as argument, as
many filenames as you would like and, then, the script will run me\_cleaner on
a batch of files specified.

The `me_cleaner` strips out AMT, networking support and many other functions in
the Intel ME firmware, while also setting ME Alt Disable and a few other bits
in the Intel Flash Descriptor, on a dumped ROM containing the Intel ME, GbE
and Flash Descriptor.

The `meclean` script automatically places the *neutered* Intel ME firmware
under `bin/neutered/filename.neutered` where `filename` was the original file
name(s) of the ROM dump(s) provided as argument(s) to the `meclean` script.

Intel ME is, in its default state, a huge security threat and should never be
used. In the past, there was no real solution on most platforms that have it.
The Retroboot project *strongly* recommends that you use `me_cleaner`. It can
also be used on systems for which no coreboot support exists, so long as the
`me_cleaner` utility has support for the Intel ME version in use on that
machine.

Basically, you dump (using SPI programmer device) the contents of boot flash
on your system. You run the dump through `me_cleaner` and it will produce a
heavily modified ROM. How heavily? A 6MiB Intel ME image is reduced to roughly
90KiB of code which merely handles initialization and power management on the
target platform.

Read more about `me_cleaner` here:
<https://github.com/corna/me_cleaner>

NOTE: On some older systems with Intel ME, the firmware can be removed entirely
from the boot flash and a few bits can be set in the Intel Flash Descriptor to
disable the Intel ME in its entirety. For example,
[Libreboot](https://libreboot.org/) supports many GM45 based laptops such as
the ThinkPad X200, X200T, T400 and so on; those systems have Intel ME, but can
be re-configured to remove the Intel ME firmware and disable it (Libreboot does
exactly that).

resources/scripts/download/memtest86plus
----------------------------------------

This script, using GNU Wget, downloads MemTest86+ and verifies the SHA512
checksum of the file. It then extracts the archive (MemTest86+ project does not
host an official Git repository).

It applies custom patches provided in `resources/memtest86plus/patch/`

The resulting source code is available at `memtest86plus/` in the Retroboot
build system.

resources/scripts/download/tianocore
------------------------------------

This script is executed when running `./download tianocore` in the Retroboot
build system.

This script downloads Tianocore. It checks out the `coreboot_fb` branch in
MrChromebox's fork of Tianocore; this is a special fork with modifications that
make Tianocore work much better as a coreboot payload (MrChromebox himself
offers pre-compiled coreboot ROMs for several systems, using Tianocore, and
thus his project competes with Retroboot; he's a really good guy btw :)

Tianocore is not downloaded to the main directory in the Retroboot build system.
This script assumes that coreboot is already downloaded, using
the `./download coreboot` command in Retroboot's build system.

This script goes into `payloads/external/tianocore/` on the coreboot build
system. Coreboot's `Makefile` for Tianocore is heavily modified so that it:

* Does not automatically download Tianocore. Such functionality is moved to
  a specific command, called `make download`
* Does not re-build Tianocore every time

Planned: fully de-couple the coreboot scripts, out of the coreboot file system
and, based on them, fully and properly integrate building and downloading of
Tianocore in the Retroboot build system. This also implies that Retroboot will
have its own toolchain (coreboot's crossgcc build scripts will be forked)
because Tianocore's build system is *extremely* temperamental.

resources/scripts/download/seabios
----------------------------------

This script downloads SeaBIOS from the following Git repository:
<https://git.seabios.org/seabios.git>

If the download fails, the script produces an error message and exits with
non-zero status.

The script resets SeaBIOS to a known revision, and does not currently apply
custom patches on top of SeaBIOS.

resources/seabios/config/
-------------------------

### resources/seabios/config/libgfxinit

This is the configuration used for SeaBIOS on coreboot configurations where
libgfxinit is used. In this configuration, SeaBIOS also compiles SeaVGABIOS.

SeaVGABIOS is a special option ROM that emulates a Video BIOS, for legacy VGA
support, but in fact uses the coreboot framebuffer, on configurations where
coreboot does its own native video initialization.

At present, SeaVGABIOS does not fully support INT10H video interrupts and does
not properly support mode switching. For example, DOS games (in FreeDOS) will
not work. However, SeaVGABIOS supports just enough functionality that, when
coreboot starts in high resolution VESA frame buffer mode, ISOLINUX and SYSLINUX
bootloader menus will display properly (which makes dealing with GNU+Linux
distributions much easier). BSD bootloader menus will probably also display
correctly with this configuration.

### resources/seabios/config/vgarom

This is the configuration used for SeaBIOS on coreboot configurations where
a PCI Option ROM is included in the coreboot ROM, for VGA support. This is used
in situations where native video initialization in coreboot is not used and/or
unavailable. The PCI Option ROM is, in this configuration, usually supplied by
the manufacturer of the video chipset; it is usually extracted from a dump of
the original vendor firmware, before coreboot is installed.

Occasionally, this Video BIOS ROM is extracted from memory on a running system.

Occasionally, this Video BIOS ROM is extracted (dumped) from an add-on
PCI/PCI-E video card. Normally, SeaBIOS will extract this at boot time but in
some situations you will want coreboot to execute it, like when using another
payload such as GNU GRUB.
